<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.20"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libxlsxwriter: Known Issues and Bugs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">libxlsxwriter
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.20 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Known Issues and Bugs </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#bugs_unreadable">Content is Unreadable. Open and Repair</a></li>
<li class="level1"><a href="#bugs_formula_name">Formulas displayed as &#39;NAME?&#39; until edited</a></li>
<li class="level1"><a href="#bugs_formula_zero">Formula results displaying as zero in non-Excel applications</a></li>
<li class="level1"><a href="#bugs_images">Images not displayed correctly in Excel 2001 for Mac and non-Excel applications</a></li>
<li class="level1"><a href="#bugs_reporting">Reporting Bugs</a><ul><li class="level2"><a href="#bugs_upgrade">Upgrade to the latest version of the library</a></li>
<li class="level2"><a href="#bugs_docs">Read the documentation</a></li>
<li class="level2"><a href="#bugs_examples">Look at the example programs</a></li>
<li class="level2"><a href="#bugs_issues">Use the xlsxwriter Issue tracker</a></li>
<li class="level2"><a href="#bugs_tips">Tips for submitting a bug report</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>This section lists known issues and bugs and gives some information on how to submit bug reports.</p>
<h1><a class="anchor" id="bugs_unreadable"></a>
Content is Unreadable. Open and Repair</h1>
<p>Very occasionally you may encounter a bug which generates an Excel warning when opening an <code>libxlsxwriter</code> file like:</p>
<blockquote class="doxtable">
<p>Excel could not open file.xlsx because some content is unreadable. Do you want to open and repair this workbook. </p>
</blockquote>
<p>This ominous sounding message is Excel's standard warning for any validation error in the XML used for the components of the XLSX file.</p>
<p>If you encounter an issue like this you should open an issue on GitHub with a program to replicate the issue (see below).</p>
<h1><a class="anchor" id="bugs_formula_name"></a>
Formulas displayed as 'NAME?' until edited</h1>
<p>Excel 2010 and 2013 added functions which weren't defined in the original file specification. These functions are referred to as <em>future</em> functions. Examples of these functions are <code>ACOT</code>, <code>CHISQ.DIST.RT</code> , <code>CONFIDENCE.NORM</code>, <code>STDEV.P</code>, <code>STDEV.S</code> and <code>WORKDAY.INTL</code>. The full list is given in the <a href="http://msdn.microsoft.com/en-us/library/dd907480%28v=office.12%29.aspx">MS XLSX extensions documentation on future functions</a>.</p>
<p>When written using <code>write_formula()</code> these functions need to be fully qualified with the <code>_xlfn.</code> prefix as they are shown in the MS XLSX documentation link above. For example:</p>
<div class="fragment"><div class="line"><a class="code" href="worksheet_8h.html#ae57117f04c82bef29805ec3eabc219bb">worksheet_write_formula</a>(worksheet, 0, 0,<span class="stringliteral">&quot;=_xlfn.STDEV.S(B1:B10)&quot;</span>, NULL);</div>
</div><!-- fragment --><p>See also <a class="el" href="working_with_formulas.html">Working with Formulas</a>.</p>
<h1><a class="anchor" id="bugs_formula_zero"></a>
Formula results displaying as zero in non-Excel applications</h1>
<p>Due to wide range of possible formulas and inter-dependencies between them, <code>xlsxwriter</code> doesn't, and realistically cannot, calculate the result of a formula when it is written to an XLSX file. Instead, it stores the value 0 as the formula result. It then sets a global flag in the XLSX file to say that all formulas and functions should be recalculated when the file is opened.</p>
<p>This is the method recommended in the Excel documentation and in general it works fine with spreadsheet applications. However, applications that don't have a facility to calculate formulas, such as Excel Viewer, or several mobile applications, will only display the 0 results.</p>
<p>If required, it is also possible to specify the calculated result of the formula using the <code><a class="el" href="worksheet_8h.html#af474c01f7ec8ac1a01206c9c4a5867af" title="Write a formula to a worksheet cell with a user defined numeric result.">worksheet_write_formula_num()</a></code> function.</p>
<p>See also <a class="el" href="working_with_formulas.html">Working with Formulas</a>.</p>
<h1><a class="anchor" id="bugs_images"></a>
Images not displayed correctly in Excel 2001 for Mac and non-Excel applications</h1>
<p>Images inserted into worksheets via <code><a class="el" href="worksheet_8h.html#a4529d77bcefcf478b8209f46fe730f6f" title="Insert an image in a worksheet cell.">worksheet_insert_image()</a></code> may not display correctly in Excel 2011 for Mac and non-Excel applications such as OpenOffice and LibreOffice. Specifically the images may looked stretched or squashed.</p>
<p>This is not an XlsxWriter issue. It also occurs with files created in Excel 2007 and Excel 2010.</p>
<h1><a class="anchor" id="bugs_reporting"></a>
Reporting Bugs</h1>
<p>Here are some tips on reporting bugs in <code>libxlsxwriter</code>.</p>
<h2><a class="anchor" id="bugs_upgrade"></a>
Upgrade to the latest version of the library</h2>
<p>The bug you are reporting may already be fixed in the latest version of the module.</p>
<p>Check the <a class="el" href="changes.html">Changes</a> section to see what has changed in the latest versions.</p>
<p>You can check which version of <code>libxlsxwriter</code> that you are using by compiling and running the following program:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;stdio.h&gt;</span></div>
<div class="line"><span class="preprocessor">#include &quot;xlsxwriter.h&quot;</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main() {</div>
<div class="line"> </div>
<div class="line">    printf(<span class="stringliteral">&quot;Libxlsxwriter version = %s\n&quot;</span>, <a class="code" href="utility_8h.html#a91acc3053f7cbe1e16872830149dc3cb">lxw_version</a>());</div>
<div class="line"> </div>
<div class="line">    <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="bugs_docs"></a>
Read the documentation</h2>
<p>Read or search the <code>libxlsxwriter</code> documentation to see if the issue you are encountering is already explained.</p>
<h2><a class="anchor" id="bugs_examples"></a>
Look at the example programs</h2>
<p>There are many <a class="el" href="examples.html">Example Programs</a> in the distribution. Try to identify an example program that corresponds to your query and adapt it to use as a bug report.</p>
<h2><a class="anchor" id="bugs_issues"></a>
Use the xlsxwriter Issue tracker</h2>
<p>The <a href="https://github.com/jmcnamara/libxlsxwriter/issues">libxlsxwriter issue tracker</a> is on GitHub.</p>
<h2><a class="anchor" id="bugs_tips"></a>
Tips for submitting a bug report</h2>
<ol type="1">
<li>Describe the problem as clearly and as concisely as possible.</li>
<li>Include a sample program. This is probably the most important step. It is generally easier to describe a problem in code than in written prose.</li>
<li>The sample program should be as small as possible to demonstrate the problem. Don't copy and paste large non-relevant sections of your program.</li>
</ol>
<p>A sample bug report is shown below. This format helps analyze and respond to the bug report more quickly. </p><pre class="fragment">Issue with SOMETHING

I am using libxlsxwriter to do SOMETHING but it appears to do SOMETHING ELSE.

I am using CC version X.Y.Z, OS = uname and libxlsxwriter x.y.z.

Here is some code that demonstrates the problem:

#include "xlsxwriter.h"

int main() {

    lxw_workbook  *workbook  = workbook_new("bug_report.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);

    worksheet_write_string(worksheet, 0, 0, "Hello", NULL);
    worksheet_write_number(worksheet, 1, 0, 123, NULL);

    return workbook_close(workbook);
}
</pre><p>Next: <a class="el" href="author.html">The library author</a> </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="autility_8h_html_a91acc3053f7cbe1e16872830149dc3cb"><div class="ttname"><a href="utility_8h.html#a91acc3053f7cbe1e16872830149dc3cb">lxw_version</a></div><div class="ttdeci">const char * lxw_version(void)</div><div class="ttdoc">Retrieve the library version.</div></div>
<div class="ttc" id="aworksheet_8h_html_ae57117f04c82bef29805ec3eabc219bb"><div class="ttname"><a href="worksheet_8h.html#ae57117f04c82bef29805ec3eabc219bb">worksheet_write_formula</a></div><div class="ttdeci">lxw_error worksheet_write_formula(lxw_worksheet *worksheet, lxw_row_t row, lxw_col_t col, const char *formula, lxw_format *format)</div><div class="ttdoc">Write a formula to a worksheet cell.</div></div>
<!-- HTML footer for doxygen 1.8.20-->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Copyright 2014-2020 John McNamara.
Generated by&#160;<a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20
</small></address>
</body>
</html>
